JBoss.orgCommunity Documentation

SS7 Stack User Guide

The guide to the JBoss Communications SS7 Stack


Preface
1. Document Conventions
1.1. Typographic Conventions
1.2. Pull-quote Conventions
1.3. Notes and Warnings
2. Provide feedback to the authors!
1. Introduction to JBoss Communications SS7 Stack
1.1. Time Division Multiplexing
2. The Basics
2.1. Shell Management client
2.2. SS7 Service
2.3. JBoss Communications SS7 Stack Usage
2.4. JBoss Communications Signaling Gateway
2.4.1. JBoss Communications M3UA Stack
3. Installation and Running
3.1. Installing
3.1.1. Binary
3.2. Installing JBoss Communications SS7 Service Binary
3.3. Running JBoss Communications SS7 Service
3.3.1. Starting
3.3.2. Stopping
3.4. Configuring JBoss Communications SS7 Service
3.4.1. Configuring M3UA
3.4.2. Configuring dahdi
3.4.3. Configuring dialogic
3.4.4. Configuring ShellExecutor
3.4.5. Configuring SCCP
3.4.6. Configuring SS7Service
3.5. Installing JBoss Communications Signaling Gateway Binary
3.6. Running JBoss Communications Signaling Gateway
3.6.1. Starting JBoss Communications Signaling Gateway
3.6.2. Start the Gateway With Alternate Configuration
3.6.3. Stopping
3.7. Configuring JBoss Communications Signaling Gateway
3.7.1. Configuring Signaling Gateway Process
3.7.2. Configuring LinksetFactory
3.7.3. Configuring LinksetManager
3.7.4. Configuring ShellExecutor
3.7.5. Configuring SignalingGateway
3.8. Setup from source
3.8.1. Release Source Code Building
3.8.2. Development Trunk Source Building
4. Hardware Setup
4.1. Sangoma
4.2. Diguim
4.3. Dialogic
5. Shell Command Line
5.1. Introduction
5.2. Starting
5.3. Linkset Management
5.3.1. Create Linkset
5.3.2. Remove Linkset
5.3.3. Activate Linkset
5.3.4. Deactivate Linkset
5.3.5. Create Link
5.3.6. Remove Link
5.3.7. Activate Link
5.3.8. Deactivate Link
5.3.9. Show status
5.4. SCCP Management
5.4.1. Rule Management
5.4.2. Address Management
5.4.3. Remote Signaling Point Management
5.4.4. Remote Sub-System Management
5.5. M3UA Management
5.5.1. M3UA Management - SGW side
5.5.2. M3UA Management - AS side
6. ISUP
6.1. ISUP Configuration
6.2. ISUP Usage
6.3. ISUP Example
7. SCCP
7.1. Routing Management
7.1.1. GTT Configuration
7.2. SCCP Usage
7.3. Access Point
7.4. SCCP User Part Example
8. TCAP
8.1. JBoss Communications SS7 Stack TCAP Usage
8.2. JBoss Communications SS7 Stack TCAP User Part Example
9. MAP
9.1. SS7 Stack MAP
9.2. SS7 Stack MAP Usage
A. Java Development Kit (JDK): Installing, Configuring and Running
B. Setting the JBOSS_HOME Environment Variable
C. Revision History
Index

This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information.

In PDF and paper editions, this manual uses typefaces drawn from the Liberation Fonts set. The Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later includes the Liberation Fonts set by default.

Four typographic conventions are used to call attention to specific words and phrases. These conventions, and the circumstances they apply to, are as follows.

Mono-spaced Bold

Used to highlight system input, including shell commands, file names and paths. Also used to highlight key caps and key-combinations. For example:

The above includes a file name, a shell command and a key cap, all presented in Mono-spaced Bold and all distinguishable thanks to context.

Key-combinations can be distinguished from key caps by the hyphen connecting each part of a key-combination. For example:

The first sentence highlights the particular key cap to press. The second highlights two sets of three key caps, each set pressed simultaneously.

If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in Mono-spaced Bold. For example:

Proportional Bold

This denotes words or phrases encountered on a system, including application names; dialogue box text; labelled buttons; check-box and radio button labels; menu titles and sub-menu titles. For example:

The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in Proportional Bold and all distinguishable by context.

Note the > shorthand used to indicate traversal through a menu and its sub-menus. This is to avoid the difficult-to-follow 'Select Mouse from the Preferences sub-menu in the System menu of the main menu bar' approach.

Mono-spaced Bold Italic or Proportional Bold Italic

Whether Mono-spaced Bold or Proportional Bold, the addition of Italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example:

Note the words in bold italics above username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system.

Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example:

If you find a typographical error in this manual, or if you have thought of a way to make this manual better, we would love to hear from you! Please submit a report in the the Issue Tracker, against the product JBoss Communications SS7 Stack , or contact the authors.

When submitting a bug report, be sure to mention the manual's identifier: SS7Stack_User_Guide

If you have a suggestion for improving the documentation, try to be as specific as possible when describing it. If you have found an error, please include the section number and some of the surrounding text so we can find it easily.

Important

Spaces where introduced in in some tables and code listings to ensure proper page render.

Common Channel Signaling System No. 7 (i.e., SS7 or C7) is a global standard for telecommunications defined by the International Telecommunication Union (ITU) Telecommunication Standardization Sector (ITU-T) . The standard defines the procedures and protocol by which network elements in the public switched telephone network (PSTN) ) exchange information over a digital signaling network to effect wireless (cellular) and wireline call setup, routing and control. The ITU definition of SS7 allows for national variants such as the American National Standards Institute (ANSI) and Bell Communications Research (Telcordia Technologies) standards used in North America and the European Telecommunications Standards Institute ( ETSI ) standard used in Europe.

The hardware and software functions of the SS7 protocol are divided into functional abstractions called "levels". These levels map loosely to the Open Systems Interconnect (OSI) 7-layer model defined by the International Standards Organization (ISO) .

SS7 Stack overview

JBoss Communications SS7 Stack is software based SS7 protocol implementation providing Level 2 and above. The JBoss Communications SS7 Stack is a platform in the sense that it does not provide the application itself but rather allows users to build the application

Important

Be aware, JBoss Communications SS7 Stack is subject to changes as it is under active development!

The JBoss Communications SS7 Stack is logically divided into two sections. The lower section includes SS7 Level 3 and below. The lower section is influenced by type of SS7 hardware (Level 1) used.

The upper section includes SS7 Level 4 and above. This logical division is widely based on flexibility of JBoss Communications SS7 Stack to allow usage of any SS7 hardware available in the market and yet JBoss Communications SS7 Stack Level 4 and above remains the same.

Further JBoss Communications SS7 Stack provides flexibility to use the Level 2,3 and Level 4 in same JVM and in same machine where SS7 Hardware (Level 1) is installed. Or its also possible to have Level 1,2,3 to be installed on separate machine and Level 4 on separate machine. In latter case M3UA over SCTP is leveraged for communication between Level 4 and Level 3 and is called JBoss Communications Signaling Gateway.

Bellow diagram shows complete JBoss Communications SS7 Stack in same machine

Bellow diagram shows JBoss Communications Signaling Gateway

Apart from advantages mentioned in

JBoss Communications SS7 Stack consists of following functional blocks:

JBoss Communications Signaling Gateway (SG) is a signaling agent that receives/sends Switched Circuit Network (SCN) native signaling at the edge of the IP network. JBoss Communications Signaling Gateway leverages JBoss Communications M3UA Stack explained in Section 2.4.1, “JBoss Communications M3UA Stack” and MTP

Diagram below shows the components which are included in JBoss Communications SG. Configuration of SG is explained in Section 3.7, “ Configuring JBoss Communications Signaling Gateway ”

M3UA is client-server protocol supporting the transport of any SS7 MTP3-User signalling (e.g., ISUP and SCCP messages) over IP. M3UA is defined by the IETF SIGTRAN working group in RFC 4666. JBoss Communications M3UA Stack can be used on Application Server side or can be used on Signaling Gateway side.

JBoss Communications SS7 stack at its core requires only Java if you are using only M3UA. However if you plan to use dahdi or dialogic SS7 hardware, respective SS7 cards needs to be installed on the server along with native libraries.

A simple way to get started is to download and install binary. This will provide you with all the dependencies you need to get going. You can obtain binary release from NOT AVAILABLE

The JBoss Communications SS7 Stack binary is broken down into a few modules.

The following is a description of the important services and libraries that make up JBoss Communications SS7 Stack

Binary release has following layout:

The upper layers of Mobicents SS7 viz., TCAP, MAP depends on JBoss Communications SS7 Service and JBoss Communications SS7 Service must be installed before upper layers can be used. The JBoss Communications SS7 Service binary requires that you have JBoss Application Server installed and JBOSS_HOME system property set. To know further details on setting JBOSS_HOME look Appendix B, Setting the JBOSS_HOME Environment Variable

Once JBOSS_HOME is properly set, use ant to deploy the mobicents-ss7-service, shell scripts and shell library.

Important

Ant 1.6 (or higher) is used to install the binary. Instructions for using Ant, including install, can be found at http://ant.apache.org/

[usr]$ cd ss7-1.0.0.BETA10/ss7
[usr]$ ant deploy
			

To undeploy these services

[usr]$ cd ss7-1.0.0.BETA10/ss7
[usr]$ ant undeploy
			

While above steps will deploy the necessary ss7 service and shell components, the java.library.path should be set to point the directory containing native component or should be copied to JBoss native library path manually. This step is only required if you are using the SS7 board on server.

Starting or stopping JBoss Communications SS7 Service is no different than starting or stopping JBoss Application Server

Once installed, you can run server by executing the run.sh (Unix) or run.bat (Microsoft Windows) startup scripts in the <install_directory>/bin directory (on Unix or Windows). If the service started properly you should see following lines in the Unix terminal or Command Prompt depending on your environment:

23:22:26,079 INFO  [LinksetManager] SS7 configuration file path /home/abhayani/workarea/mobicents/jboss-5.1.0.GA/server/default/data/linksetmanager.xml
23:22:26,141 INFO  [LinksetManager] Started LinksetManager
23:22:26,199 INFO  [SS7Service] Starting SCCP stack...
23:22:26,229 INFO  [SccpStackImpl] Starting ...
23:22:26,230 INFO  [RouterImpl] SCCP Router configuration file: /home/abhayani/workarea/mobicents/jboss-5.1.0.GA/server/default/deploy/mobicents-ss7-service/sccp-routing.txt
23:22:26,261 INFO  [SS7Service] SCCP stack Started. SccpProvider bound to java:/mobicents/ss7/sccp
23:22:26,261 INFO  [ShellExecutor] Starting SS7 management shell environment
23:22:26,270 INFO  [ShellExecutor] ShellExecutor listening at /127.0.0.1:3435
23:22:26,270 INFO  [SS7Service] [[[[[[[[[ Mobicents SS7 service started ]]]]]]]]]

				

If you have started ss7-1.0.0.BETA10 for the first time, SS7 is not configured. You need to use Shell Client to connect to ss7-1.0.0.BETA10 as defined in Chapter 5, Shell Command Line . With CLI you can configure how service interacts with SS7 network, that is you configure either installed SS7 card and its native library\ , or M3UA layer.

Once the configured, the state and configuration of SS7 is persisted which stands server re-start.

Configuration is done through an XML descriptor named jboss-beans.xml and is located at $JBOSS_HOME/server/profile_name/deploy/mobicents-ss7-service/META-INF, where profile_name is the server profile name.

The JBoss Communications SS7 Layer 4 (SCCP, ISUP) leverages either of following MTP layers to exchange signalling messages with remote signalling points

The ss7 service will be configured with either of these services.

ClientM3UAProcess is only needed if the underlying SS7 service will leverage M3UA. ClientM3UAProcess acts as remote Signaling Gateway Process. M3UAShellExecutor accepts the M3UA commands and executes necessary operations. ClientM3UAManagement contains the list of Application Server (AS) (and list of Application Server Process (ASP) within each AS) connecting to external Signaling Gateway (SG) and also manages them.



    <!-- ==================================================================== -->
    <!-- M3UA                                                                 -->
    <!-- ClientM3UAManagement is managing the ASP side commands               -->
    <!-- ==================================================================== -->
    <bean name="ClientM3UAManagement"
        class="org.mobicents.protocols.ss7.m3ua.impl.as.ClientM3UAManagement">
        <property name="persistDir">${jboss.server.data.dir}</property>
    </bean>

    <bean name="M3UAShellExecutor"
        class="org.mobicents.protocols.ss7.m3ua.impl.oam.M3UAShellExecutor">
        <property name="m3uaManagement">
            <inject bean="ClientM3UAManagement" />
        </property>
    </bean>

    <bean name="Mtp3UserPart"
        class="org.mobicents.protocols.ss7.m3ua.impl.as.ClientM3UAProcess">
        <property name="clientM3UAManagement">
            <inject bean="ClientM3UAManagement" />
        </property>
    </bean>
                        

ClientM3UAManagement when started looks for file's m3ua-client.xml and m3ua-clientroute.xml. The m3ua-client.xml contains serialized information about AS and ASP configured for this ClientM3UAProcess. The m3ua-clientroute.xml contains serialized information about defined routes.

Route maintains the availability status of a remote Point Code in the SS7 network via one or more Signaling Gateways. Application Hosts connecting to Signaling Gateways will require the configuration of Routes for each Remote Signaling Point Code they wish to communicate with.

Dahdi based MTP layer will only be used when you have installed dahdi based SS7 hardware (Sangoma or Diguim cards). DahdiLinksetFactory is responsible to create new instances of corresponding DahdiLinkset when instructed by LinksetManager.

LinksetFactoryFactory is just a call-back class listening for new factories deployed and maintains Map of available factory name vs factory. You should never touch this bean.

ShellExecutor is responsible for listening to incoming command. Received commands are executed on local resources to perform actions like creation and management of SCCP routing rule, creation and management of Linkset, management of M3UA stack.


<!-- ================================================ -->
    <!-- Shell Service                                                        -->
    <!-- ================================================ -->
    <!-- Define Shell Executor -->
    <bean name="ShellExecutor"
        class="org.mobicents.ss7.ShellExecutor">
        <property name="address">${jboss.bind.address}</property>
        <property name="port">3435</property>
        <!-- LinksetExecutor required only if dahdi based hardware is installed. -->
        <property name="linksetExecutor">
            <inject bean="LinksetExecutor" />
        </property>
        <!-- M3UAShellExecutor required only if M3UA will be leveraged. -->
        <property name="m3UAShellExecutor">
            <inject bean="M3UAShellExecutor" />
        </property>
        <!-- To manage SCCP resource and rules -->
        <property name="sccpExecutor">
            <inject bean="SccpExecutor" />
        </property>
    </bean>

By default ShellExecutor listens at jboss.bind.address and port 3435. You may set the address property to any valid IP address that your host is assigned. The shell commands are exchanged over TCP/IP.

As name suggests SccpStack initiates the SCCP stack routines. Stack has following properties:

SccpExecutor accepts sccp commands and executes necessary operations

SccpProvider is bound to JNDI by SS7 Service and is used by upper layers


    <!-- ==================================================================== -->
    <!-- SCCP Router Service -->
    <!-- ==================================================================== -->
    <!--Define Router for SCCP -->
    <bean name="Router" class="org.mobicents.protocols.ss7.sccp.impl.router.Router">
        <property name="persistDir">${jboss.server.data.dir}</property>
    </bean>

    <bean name="SccpResource" class="org.mobicents.protocols.ss7.sccp.impl.SccpResource">
        <property name="persistDir">${jboss.server.data.dir}</property>
    </bean>

    <bean name="SccpExecutor"
        class="org.mobicents.protocols.ss7.sccp.impl.oam.SccpExecutor">
        <property name="router">
            <inject bean="Router" />
        </property>
        <property name="sccpResource">
            <inject bean="SccpResource" />
        </property>
    </bean>

    <bean name="SccpStack" class="org.mobicents.protocols.ss7.sccp.impl.SccpStackImpl">
        <property name="localSpc">2</property>
        <property name="ni">2</property>
        <property name="router">
            <inject bean="Router" />
        </property>
        <property name="sccpResource">
            <inject bean="SccpResource" />
        </property>
        <property name="mtp3UserPart">
            <inject bean="Mtp3UserPart" />
        </property>
    </bean>

    <bean name="SccpProvider"
        class="org.mobicents.protocols.ss7.sccp.impl.SccpProviderImpl">
        <constructor factoryMethod="getSccpProvider">
            <factory bean="SccpStack" />
        </constructor>
    </bean>

SS7Service acts as core engine binding all the components together. To get holistic view of SS7 Service look at Section 2.2, “SS7 Service”


    <!-- ==================================================================== -->
    <!-- Mobicents SS7 Service -->
    <!-- ==================================================================== -->
    <bean name="SS7Service" class="org.mobicents.ss7.SS7Service">
        <annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX(name=
              "org.mobicents.ss7:service=SS7Service",
              exposedInterface=org.mobicents.ss7.SS7ServiceMBean.class,
              registerDirectly=true)</annotation>
        <property name="jndiName">java:/mobicents/ss7/sccp</property>
        <property name="stack">
            <inject bean="SccpProvider" />
        </property>
    </bean>

SS7 service binds SccpProvider to JNDI java:/mobicents/ss7/sccp. The JNDI name can be configured to any valid JNDI name specific to your application.

In the Linux terminal or Windows command prompt, the JBoss Communications Signaling Gateway has started successfully if the last line of output is similar to the following

15:51:18,247 INFO  [MainDeployer] [[[[[[[[[ Mobicents Signaling Gateway: release.version=1.0.0.BETA10 Started ]]]]]]]]]

Configuration is done through an XML descriptor named sgw-beans.xml and is located at mobicents-sgw/deploy,

JBoss Communications SS7 Stack is an open source project, instructions for building from source are part of the manual! Building from source means you can stay on top with the latest features. Whilst aspects of JBoss Communications SS7 Stack are quite complicated, you may find ways to become contributors.

JBoss Communications SS7 Stack works with JDK1.5 and above (If using M3UA, JDK1.7 and above ). you will also need to have the following tools installed. Minimum requirement version numbers provided.

  1. Downloading the source code

    Use SVN to checkout a specific release source, the base URL is ?, then add the specific release version, lets consider 1.0.0.BETA10.

    [usr]$ svn co ?/ss7-1.0.0.BETA10
  2. Building the source code

    Now that we have the source the next step is to build and install the source. JBoss Communications SS7 Stack uses Maven 2 to build the system. There are three profiles. Default one builds only java source. The other two profiles available "dahdilinux" and "dialogiclinux" additionaly compile native modules.

    Use "dahdilinux" profile if linux server on which this code is built already has dahdi module installed. Make sure you pass "include.zap" system property pointing to correct directory where dahdi is installed

    [usr]$ cd ss7-1.0.0.BETA10
    [usr]$ mvn install -Pdahdilinux -Dinclude.zap=/usr/include/dahdi
    				    

    Use "dialogiclinux" profile if linux server on which this code is built already has dialogic module installed. Make sure you pass "include.dialogic" and "include.dialogic.gctlib" system property pointing to correct directory where dialogic libraries are installed. include.dialogic.gctlib points to directory where gctload is present (generally /opt/dpklnx for linux OS)

    [usr]$ cd ss7-1.0.0.BETA10
    [usr]$ mvn install -Pdialogclinux -Dinclude.dialogic=/opt/dpklnx/INC -Dinclude.dialogic.gctlib=/opt/dpklnx
    				    

    To build JBoss Communications SS7 Stack without building any native libraries use

    [usr]$ cd ss7-1.0.0.BETA10
    [usr]$ mvn install 
    				    

    Use Ant to build the binary .

    [usr]$ cd ss7-1.0.0.BETA10/release
    [usr]$ ant
    				    

This chapter contains reference to configure hardware drivers for different types of SS7 cards.

JBoss Communications SS7 Stack supports dahdi based SS7 cards like diguim and sangoma. Generally dahdi based SS7 crads doesn't have MTP2/MTP3 support on board and relies on external software to provide these services.

JBoss Communications SS7 Stack also supports dialogic based SS7 cards which has on board support for MTP2/MTP3

Linksets are managed by linkset command. It allows to perform following:

SCCP provides connectionless and connection-oriented network services. This includes address(GTT) translation and routing, flow control segmentation and reassembly.

A global title is an address (e.g., a dialed 800 number, calling card number, or mobile subscriber identification number) which is translated by SCCP into a destination point code and subsystem number. A subsystem number uniquely identifies an application at the destination signaling point. SCCP is used as the transport layer for TCAP -based services

As SCCP acts as message router, it requires means to configure routing information. CLI provides way to easily manage routing rules information in JBoss Communications SCCP implementation.

User should also configure the remote subsystem number and remote signaling pointcode. In some cases where global title is used, SCCP will only require configuring of remote signaling pointcode and configuring of remote subsystem is not required.

SCCP routing rules are managed by sccp rule command. It allows to perform following:

Rule can be create by issuing command with following structure:

sccp rule create <id> <mask> <address-indicator> <point-code> <subsystem-number> <translation-type> <numbering-plan>  
<nature-of-address-indicator> <digits> <primary-address-id> <backup-address-id>

This command should be specified after primary_add and backup_add are configured. Please refer Section 5.4.2, “Address Management” on how to configure primary_add and backup_add

<id>

A unique number to identify this rule

<mask>

mask defines which part of the originally dialed digits remains in the translated digits and which part is replaced by the digits from primary or backup address. mask is divided into sections by separator /. The number of sections in mask should be equal to sections in digits passed in this command and sections in primary or backup address


<address-indicator>

The address indicator is the first field in SCCP Party Address(called/calling) and is one octet in length. Its function is to indicate which information elements are present so that the address can be interpreted, in other words, it indicates the type of addressing information that is to be found in the address field. The addressing information from original global title is then compared with passed address information to match the rule.

<point-code>

Point code. This is ignored if bit 0 of address-indicator is not set.

<subsystem-number>

Subsystem Number. This is ignored if bit 1 of address-indicator is not set.

<translation-type>

Translation type. This is ignored if GT Indicator is 0000 or 0001


<numbering-plan>

The Number Plan (NP) field specifies the numbering plan that the address information follows. This is ignored if GT Indicator is 0000, 0001 or 0010

<nature-of-address-indicator>

The Nature of Address Indicator (NAI) field defines the address range for a specific numbering plan. This is only used if GT Indicator is 0100

<digits>

Specifies the string of digits divided into subsections using separator '/' depending on if mask contains separator. The dialed digits should match with theses digits as per rule specified bellow


<primary-address-id>

Identifies the SCCP Address used as the primary translation

<backup-address-id>

Identifies the SCCP Address used as the backup translation incase if pointcode specified by primary address is not available


The command is used to define primary or backup address of translation. The global title address information of this command is combined with the global title being translated by examining the mask provided in the sccp rule create command.The syntanx remains same except for primary address sccp primary_add is used and for backup address sccp backup_add is used

Address can be create by issuing command with following structure:

<id>

A unique number to identify this address

<address-indicator>

The address indicator is the first field in SCCP Party Address(called/calling) and is one octet in length. Its function is to indicate which information elements are present so that the address can be interpreted, in other words, it indicates the type of addressing information that is to be found in the address field. The addressing information from original global title is then compared with passed address information to match the rule.

<point-code>

Point code. This is ignored if bit 0 of address-indicator is not set.

<subsystem-number>

Subsystem Number. This is ignored if bit 1 of address-indicator is not set.

<translation-type>

Translation type. This is ignored if GT Indicator is 0000 or 0001


<numbering-plan>

The Number Plan (NP) field specifies the numbering plan that the address information follows. This is ignored if GT Indicator is 0000, 0001 or 0010

<nature-of-address-indicator>

The Nature of Address Indicator (NAI) field defines the address range for a specific numbering plan. This is only used if GT Indicator is 0100

<digits>

The global title address information to translate to, specified as string of digits divided into subsections using separator '/' depending on if mask contains separator.

In addition the digits string can contain




Commands to manage JBoss Communications M3UA Stack used on Application Server (AS) side differs from commands to manage JBoss Communications M3UA Stack used on Signaling Gateway side (SGW).

M3UA - SGW side is managed by m3ua command. It allows to perform following:

Remote Application Server (AS) can be created by issuing command with following structure:

m3ua ras create rc <routing-context> rk dpc <destination point code> opc <originating point code> 
			                si <service indicator> traffic-mode <traffic mode> <ras-name>

Where:


M3UA - AS side is managed by m3ua command. It allows to perform following:

ISUP( ISDN User Part or ISUP ) is part of SS7 which is used to establish telephone calls and manage call switches( exchanges). Exchanges are connected via E1 or T1 trunks. Each trunk is divided by means of TDM into time slots. Each time slot is distinguished as circuit. Circuits (identified by code) are used as medium to transmit voice data between user equipment (or exchanges if more than one is involved).

ISUP allows not only to setup a call, but to exchange information about exchange state and its resources(circuits).

Note

JBoss Communications ISUP is based on ITU-T Q.76X series of documents.

JBoss Communications ISUP stack is configured with simple properties. Currently following properties are supported:

Table 6.1. ISUP Configuration options

NameDefault valueValue rangeDescription
niNone, must be provided0-3Sets value of network indicator that should be used by stack.
localspcNone, must be provided0 - (2^14)-1Sets local signaling point code. It will be used as OPC for outgoing signaling units.
t14s4s - 15sSets T1 value. Started when REL is sent. See A.1/Q.764
t55 min.5min - 15 minSets T5 value. Started when initial REL is sent. See A.1/Q.764
t720s20s -30sSets T7 value. (Re)Started when Address Message is sent. See A.1/Q.764
t1215s15s - 60s Sets T12 value. Started when BLO is sent. See A.1/Q.764
t135min5min - 15minSets T13 value. Started when initial BLO is sent. See A.1/Q.764
t145s15s - 60sSets T14 value. Started when UBL is sent. See A.1/Q.764
t155min5min - 15minSets T15 value. Started when initial UBL is sent. See A.1/Q.764
t165s15s - 60sSets T16 value. Started when RSC is sent. See A.1/Q.764
t175min5min - 15minSets T17 value. Started when initial RSC is sent. See A.1/Q.764
t185s15s - 60sSets T18 value. Started when CGB is sent. See A.1/Q.764
t195min5min - 15minSets T19 value. Started when initial CGB is sent. See A.1/Q.764
t205s15s - 60sSets T20 value. Started when CGU is sent. See A.1/Q.764
t215min5min - 15minSets T21 value. Started when initial CGU is sent. See A.1/Q.764
t225s15s - 60sSets T22 value. Started when GRS is sent. See A.1/Q.764
t235min5min - 15minSets T23 value. Started when initial GRS is sent. See A.1/Q.764
t2810s10sSets T28 value. Started when CQM is sent. See A.1/Q.764
t3312s12s - 15sSets T33 value. Started when INR is sent. See A.1/Q.764

Note that before start user must provide two interfaces to stack:

Mtp3UserPart

implementation of transport layer which should be used by stack

CircuitManager

circuit manager implementation. This interface stores information on mapping between CIC(Circuit Identification Code) and DPC(Destination Point Code) used as destination for outgoing messages.

Below is simple example of stack usage:




import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;
import java.util.Properties;
import org.mobicents.protocols.ss7.isup.ISUPEvent;
import org.mobicents.protocols.ss7.isup.ISUPListener;
import org.mobicents.protocols.ss7.isup.ISUPProvider;
import org.mobicents.protocols.ss7.isup.ISUPStack;
import org.mobicents.protocols.ss7.isup.ISUPTimeoutEvent;
import org.mobicents.protocols.ss7.isup.ParameterException;
import org.mobicents.protocols.ss7.isup.impl.ISUPStackImpl;
import org.mobicents.protocols.ss7.isup.message.ISUPMessage;    
import org.mobicents.ss7.linkset.oam.Layer4;
import org.mobicents.ss7.linkset.oam.Linkset;
public class ISUPTest implements ISUPListener
{
    protected ISUPStack stack;
    protected ISUPProvider provider;
    protected Linkset isupLinkSet;
    
    
    public void setUp() throws Exception {
        
        this.isupLinkSet = ....; //same linksets as in SS7Service
        this.stack = new ISUPStackImpl();
        this.stack.configure(getSpecificConfig());
        this.provider = this.stack.getIsupProvider();
        this.provider.addListener(this);
        Mtp3UserPart userPart = // create with proper factory, dahdii, dialogi, m3ua
        this.stack.setMtp3UserPart(userPart);
        CircuitManagerImpl circuitManager = new CircuitManagerImpl();
        circuitManager.addCircuit(1, 431613); // CIC - 1, DPC for it - 431613
        
        
        this.stack.setCircuitManager(circuitManager);
        this.stack.start();
    }
    
    
    public void onEvent(ISUPEvent event) {
        ISUPMessage msg = event.getMessage();
        switch(msg.getCircuitIdentificationCode().getCIC())
        {
            case AddressCompleteMessage._COMMAND_CODE:
            //only complete
            break;
            case ConnectedMessage._COMMAND_CODE:
            case AnswerMessage._COMMAND_CODE:
            //we are good to go
            ConnectedNumber cn = (ConnectedNumber)msg.getParameter(ConnectedNumber._PARAMETER_CODE);
            //do something
            break;
            case ReleaseMessage._COMMAND_CODE:
            //remote end does not want to talk 
            RealeaseCompleteMessage rlc = provider.getMessageFactory().createRLC();
            rlc.setCircuitIdentificationCode(msg.getCircuitIdentificationCode());
            rlc.setCauseIndicators(   ((ReleaseComplete)msg).getCauseIndicators());
            provider.sendMessage(rlc);
            
        }
    }
    public void onTimeout(ISUPTimeoutEvent event) {
        switch(event.getTimerId())
        {
            case ISUPTimeoutEvent.T1:
                //do something
                break;
            case ISUPTimeoutEvent.T7:
                //do even more
                break;
        }
    }
}
        
    

The Signaling Connection Control Part (SCCP) is defined in ITU-T Recommendations Q.711-Q.716. SCCP sits on top of Message Transfer Part 3 (MTP3) in the SS7 protocol stack. The SCCP provides additional network layer functions to provide transfer of noncircuit-related (NCR) signaling information, application management procedures and alternative, more flexible methods of routing.

SCCP provides a routing function that allows signaling messages to be routed to a signaling point based on dialed digits, for example. This capability is known as Global Title Translation (GTT), which translates what is known as a global title (for example, dialed digits for a toll free number) into a signaling point code and a subsystem number so that it can be processed at the correct application.

Routing rules are configured using the Command Line Interface as explained Section 5.4, “SCCP Management”

GTT is performed in two stages. First is matching the rule and second is actual translation.

For matching the rule, the called party address global title digits are matched with <digits> configured in sccp rule create Section 5.4.1.1, “Create Rule” command above. Once the digits match actual translation is done

Matching rule

As explained in sccp rule create Section 5.4.1.1, “Create Rule” command the <digits> can be divided into sections using the "/" separate character. Each section defines set of digits to be matched. Wild card * can be used to match any digits and ? can be used to match exatcly one digit

For example Rule is to match starting 4 digits (should be 1234) and doesn't care for rest; the <digits> in the command will be 1234/*. If the Rule is such that starting 3 digits should be 123, doesn't care for other three digits but last two digits should be 78; the <digits> in the command will be 123/???/78. If digit to digit matching is needed the the <digits> in the command will be exact digits to be matched without sections.

Translation

For translation each section in <mask> defined in sccp rule create command defines how replacement operation is performed. If <mask> defines K, the originally dialed digits are kept and if <mask> defines R the digits from primary address or back address are used. The primary/backup address should always define the point code and the translated address will always have this point code. If the primary/backup address defines the subsystem number the translated address will also have this subsystem number. The address-indicator of translated address is always from primary/backup address. See bellow examples

The instance of org.mobicents.protocols.ss7.sccp.SccpStack acts as starting point. All the sccp messages sent by SCCP User Part are routed as per the rule configured in Router

The SCCP User Part gets handle to SccpStack by doing JNDI look-up as explained in Section 7.3, “Access Point”

SccpStack exposes org.mobicents.protocols.ss7.sccp.SccpProvider that interacts directly with SccpStack. This interface defines the methods that will be used by SCCP User Part to send org.mobicents.protocols.ss7.sccp.message.SccpMessage and register org.mobicents.protocols.ss7.sccp.SccpListener's to listen for incoming SCCP messages.

SCCP User Part registers SccpListener for specific local subsystem number. For every incoming SccpMessage, if the called subsystem matches with this local subsystem, the corresponding SccpListner is called.

SccpProvider also exposes org.mobicents.protocols.ss7.sccp.message.MessageFactory and org.mobicents.protocols.ss7.sccp.parameter.ParameterFactory to create new concrete SccpMessage viz., org.mobicents.protocols.ss7.sccp.message.UnitData or org.mobicents.protocols.ss7.sccp.message.XUnitData passing the corresponding parameters created by leveraging ParameterFactory.

SS7 Service provides user with access point to SCCP protocol/stack.

To get handle to SccpStack do the JNDI look-up passing the JNDI name configured in SS7 service as explained in Section 3.4.6, “Configuring SS7Service”

    

        private static SccpProvider getSccpProvider() throws NamingException {
    
            // no arg is ok, if we run in JBoss
            InitialContext ctx = new InitialContext();
            try {
                String providerJndiName = "/mobicents/ss7/sccp";
                return ((SccpStack) ctx.lookup(providerJndiName)).getSccpProvider();
    
            } finally {
                ctx.close();
            }
        }
            
        

Below is SCCP User Part example listening for incoming SCCP message and sending back new message



public class Test implements SccpListener {
    private SccpProvider sccpProvider;
    private SccpAddress localAddress;
    private static SccpProvider getSccpProvider() throws NamingException {
        // no arg is ok, if we run in JBoss
        InitialContext ctx = new InitialContext();
        try {
            String providerJndiName = "/mobicents/ss7/sccp";
            return ((SccpStack) ctx.lookup(providerJndiName)).getSccpProvider();
        } finally {
            ctx.close();
        }
    }
    public void start() throws Excetpion {
        this.sccpProvider = getSccpProvider();
        int translationType = 0;
        int subSystemNumber = 0;
        GlobalTitle gt = GlobalTitle.getInstance(translationType,
                NumberingPlan.ISDN_MOBILE, NatureOfAddress.NATIONAL, "1234");
        localAddress = new SccpAddress(gt, 0);
        this.sccpProvider.registerSccpListener(localAddress, this);
    }
    public void stop() {
        this.sccpProvider.deregisterSccpListener(localAddress);
    }
    public void onMessage(SccpMessage message) {
        if (message.getType() == MessageType.UDT) {
            throw new IlleagalArgumentException("Dont like UDT");
        } else if (message.getType() == MessageType.XUDT) {
            XUnitData xudt = (XUnitData) message;
            localAddress = ((XUnitData) message).getCalledPartyAddress();
            SccpAddress remoteAddress = ((XUnitData) message)
                    .getCallingPartyAddress();
            // now decode content
            byte[] data = xudt.getData();
            // some data encoded in
            CallRequest cr = new CallRequest(data);
            byte[] answerData;
            if (cr.getCallee().equals(this.localAddress)) {
                EstablihsCallAnswer eca = new EstablihsCallAnswer(cr);
                answerData = eca.encode();
            } else {
                TearDownCallAnswer tdca = new TearDownCallAnswer(cr);
                answerData = tdca.encode();
            }
            HopCounter hc = this.sccpProvider.getParameterFactory()
                    .createHopCounter(5);
            XUnitData sccpAnswer = this.sccpProvider
                    .getMessageFactory()
                    .createXUnitData(hc, xudt.getProtocolClass(),
                            message.getCallingPartyAddress(), this.localAddress);
            this.sccpProvider.send(sccpAnswer);
        }
    }
}
        

The Transaction Capabilities Application Part (TCAP) is defined in ITU-T Recommendations Q.771-Q.775. TCAP allows services at network nodes to communicate with each other using an agreed-upon set of data elements. Its primary purpose is to facilitate multiple concurrent dialogs between the same sub-systems on the same machines, using Transaction IDs to differentiate these, similar to the way TCP ports facilitate multiplexing connections between the same IP addresses on the Internet.

The org.mobicents.protocols.ss7.tcap.api.TCAPStack interface defines the methods required to represent TCAP Protocol Stack. TCAPStack exposes org.mobicents.protocols.ss7.tcap.api.TCAPProvider that interacts directly with TCAPStack. TCAPProvider defines methods that will be used by TCAP User Part to create new org.mobicents.protocols.ss7.tcap.api.tc.dialog.Dialog to be sent across network. TCAP User Part also allows to registerorg.mobicents.protocols.ss7.tcap.api.TCListener to listen TCAP messages.

TCAPProvider also exposes org.mobicents.protocols.ss7.tcap.api.DialogPrimitiveFactory to create dialog primitives and org.mobicents.protocols.ss7.tcap.api.ComponentPrimitiveFactory to create components. Components are a means of invoking an operation at a remote node

The UML Class Diagram looks like

The org.mobicents.protocols.ss7.tcap.TCAPStackImpl is concrete implementation of TCAPStack. The TCAP User Part creates instance of TCAPStackImpl passing the reference of SccpProvider and new instance of SccpAddress representing address to which bind listener. The TCAP stack creates internaly JBoss Communications MAP Stack implementation. Passed SccpAddress is used to match against incoming messages destination address.

    

            SccpProvider sccpProvider = getSccpProvider(); //JNDI lookup of SCCP Stack and get Provider
            SccpAddress localAddress createLocalAddress();      
    
            TCAPStack tcapStack = new TCAPStackImpl(sccpPprovider, localAddress);
    
              
            ...
            
            private SccpAddress createLocalAddress()
            {
                
                return new SccpAddress(RoutingIndicator.ROUTING_BASED_ON_DPC_AND_SSN, 1, null, 8);
            }
    
            
        

The reference to SccpProvider is received from SccpStack. To get handle to SccpStack do the JNDI look-up passing the JNDI name configured in SS7 service as explained in Section 7.3, “Access Point”

The TCAP User Part should register the concrete implementation of TCListener with TCAPProvider to listen for incoming TCAP messages.



    public class Client implements TCListener{
            .....       
            tcapProvider = tcapStack.getProvider();
            tcapProvider.addTCListener(this);
            ....
    }               
            
        

The TCAP User Part leverages TCAPProvider to create new Dialog. The component's between the nodes are exchanged within this Dialog



        clientDialog = this.tcapProvider.getNewDialog(thisAddress, remoteAddress);          
        
    

The TCAP User Part leverages ComponentPrimitiveFactory to create new components. These components are sent usig the dialog



        //create some INVOKE
        Invoke invoke = cpFactory.createTCInvokeRequest();
        invoke.setInvokeId(this.clientDialog.getNewInvokeId());
        OperationCode oc = cpFactory.createOperationCode();
        oc.setLocalOperationCode(12L);
        invoke.setOperationCode(oc);
        //no parameter
        this.clientDialog.sendComponent(invoke);        
        
    

Below is TCAP User Part example. This example creates dialog and exchanges messages withing structured dialog. Refer to source for function calls:

    

        
public class Client implements TCListener{
    //encoded Application Context Name
    public static final long[] _ACN_ = new long[] { 0, 4, 0, 0, 1, 0, 19, 2 };
    
    private TCAPStack stack;
    private SccpAddress thisAddress;
    private SccpAddress remoteAddress;
    
    private TCAPProvider tcapProvider;
    private Dialog clientDialog;
    
    Client(SccpProvider sccpPprovider, SccpAddress thisAddress,SccpAddress remoteAddress) {
        super();
        this.stack = new TCAPStackImpl(sccpPprovider,thisAddress); //pass address, so stack can register in SCCP
        this.runningTestCase = runningTestCase;
        this.thisAddress = thisAddress;
        this.remoteAddress = remoteAddress;
        this.tcapProvider = this.stack.getProvider();
        this.tcapProvider.addTCListener(this);
    }
    private static SccpProvider getSccpProvider() throws NamingException {
        // no arg is ok, if we run in JBoss
        InitialContext ctx = new InitialContext();
        try {
            String providerJndiName = "/mobicents/ss7/sccp";
            return ((SccpStack) ctx.lookup(providerJndiName)).getSccpProvider();
        } finally {
            ctx.close();
        }
    }
    public void start() throws TCAPException, TCAPSendException {
        clientDialog = this.tcapProvider.getNewDialog(thisAddress, remoteAddress);
        ComponentPrimitiveFactory cpFactory = this.tcapProvider.getComponentPrimitiveFactory();
        
        //create some INVOKE
        Invoke invoke = cpFactory.createTCInvokeRequest();
        invoke.setInvokeId(this.clientDialog.getNewInvokeId());
        
        OperationCode oc = cpFactory.createOperationCode();
        oc.setLocalOperationCode(12L);
        invoke.setOperationCode(oc);
        //no parameter
        this.clientDialog.sendComponent(invoke);
        
        ApplicationContextName acn = this.tcapProvider.getDialogPrimitiveFactory()
            .createApplicationContextName(_ACN_);
        //UI is optional!
        TCBeginRequest tcbr = this.tcapProvider.getDialogPrimitiveFactory().createBegin(this.clientDialog);
        tcbr.setApplicationContextName(acn);
        this.clientDialog.send(tcbr);
    }
    public void onDialogReleased(Dialog d)
    {
        d.keepAlive();
    }
    public void onInvokeTimeout(Invoke tcInvokeRequest)
    {
    }
    
    public void onDialogTimeout(Dialog d)
    {
    }
    public void onTCBegin(TCBeginIndication ind) {
        
        
    }
    public void onTCContinue(TCContinueIndication ind) {
        //send end
        TCEndRequest end = this.tcapProvider.getDialogPrimitiveFactory().createEnd(ind.getDialog());
        end.setTermination(TerminationType.Basic);
        try {
            ind.getDialog().send(end);
            
        } catch (TCAPSendException e) {
            throw new RuntimeException(e);
        }
    }
    public void onTCEnd(TCEndIndication ind) {
        //should not happen, in this scenario, we send data.
    }
    public void onTCUni(TCUniIndication ind) {
        //not going to happen
    
    }
    public void onTCPAbort(TCPAbortIndication ind) {
        // TODO Auto-generated method stub
        
    }
    public void onTCUserAbort(TCUserAbortIndication ind) {
        // TODO Auto-generated method stub
        
    }
    
    
    public static void main(String[] args)
    {
        SccpAddress localAddress = new SccpAddress(RoutingIndicator.ROUTING_BASED_ON_DPC_AND_SSN, 1, null, 8);
        
       
        SccpAddress remoteAddress = new SccpAddress(RoutingIndicator.ROUTING_BASED_ON_DPC_AND_SSN, 2, null, 8);
        Client c = new Client(getSccpProvider(),localAddress,remoteAddress);
    }
    
}
        
        

Mobile application part (MAP) is the protocol that is used to allow the GSM network nodes within the Network Switching Subsystem (NSS ) to communicate with each other to provide services, such as roaming capability, text messaging (SMS), Unstructured Supplementary Service Data ( USSD) and subscriber authentication. MAP provides an application layer on which to build the services that support a GSM network. This application layer provides a standardized set of services. MAP uses the services of the SS7 network, specifically the Signaling Connection Control Part (SCCP ) and the Transaction Capabilities Application Part (TCAP)

Important

For better understanding of this chapter please read GSM 09.02.

Note

JBoss Communications SS7 Stack MAP has implementation for USSD, SMS and Location Management Service (LMS) Messages only. Any contribution to implement other messages are welcome. We will provide you all the help that you may need initially.

The org.mobicents.protocols.ss7.map.api.MAPStack interface defines the methods required to represent MAP Protocol Stack. MAPStack exposes org.mobicents.protocols.ss7.map.api.MAPProvider that interacts directly with MAPStack. This interface defines the methods that will be used by any registered MAP User application implementing the org.mobicents.protocols.ss7.map.api.MAPDialogListener and org.mobicents.protocols.ss7.map.api.MAPServiceListener interface to listen MAP messages and dialogue handling primitives.

Each MAP-User interested in listening messages specific to MAP Service implements specific MAPServiceListener.

MAP-User interested in all the services may implement all the service listener class.

The org.mobicents.protocols.ss7.map.MAPStackImpl is concrete implementation of MAPStack. The MAP User application creates instance of MAPStackImpl passing the reference of SccpProvider and Sub System Number. All incoming messages are checked for destination SSN, if it matches with the one registered with this MAPStackImpl the corresponding listener is called else the peer receives error.

SccpProvider sccpProvider = getSccpProvider(); //JNDI lookup of SCCP Stack and get Provider

        MAPStackImpl mapStack = new MAPStackImpl(sccpPprovider, 8);
        ...
        

The reference to SccpProvider is received from SccpStack. To get handle to SccpStack do the JNDI look-up passing the JNDI name configured in SS7 service as explained in Section 7.3, “Access Point”

The MAP User application should register the concrete implementation of MAPDialogListener with MAPProvider to listen for incoming MAP Dialog and MAP Primitive messages.

The MAP User application should register the concrete implementation of MAPServiceListener with corresponding MAPServiceBase to listen for incoming MAP Service messages. Following MAPServiceBase are exposed by MAPProvider

  • For LSM service org.mobicents.protocols.ss7.map.api.service.lsm.MAPServiceLsm

  • For SMS service org.mobicents.protocols.ss7.map.api.service.sms.MAPServiceSms

  • For USSD service org.mobicents.protocols.ss7.map.api.service.supplementary.MAPServiceSupplementary



public class MAPExample implements MAPDialogListener, MAPServiceSupplementaryListener {
        .....       
        mapProvider = mapStack.getMAPProvider();
        mapProvider.addMAPDialogListener(this);
        mapProvider.getMAPServiceSupplementary().addMAPServiceListener(this);
        ....
} 
    

Before any MAP specific service can be used, the corresponding service should be activated



        .....       
        // Make the supplimentary service activated
        mapProvider.getMAPServiceSupplementary().acivate();
        ....
    

The MAP User Application leverages MapServiceFactory to create instance of USSDString and AddressString



        MapServiceFactory servFact = mapProvider.getMapServiceFactory();
        USSDString ussdString = servFact.createUSSDString("*125*+31628839999#",
                null);
        AddressString msisdn = this.servFact.createAddressString(
                AddressNature.international_number, NumberingPlan.ISDN,
                "31628838002");
    

The MAP User Application leverages specific MAPServiceBase to create new MAPDialog and send message



        // First create Dialog
        MAPDialogSupplementary mapDialog = mapProvider.getMAPServiceSupplementary().createNewDialog(
                MAPApplicationContext.getInstance(MAPApplicationContextName.networkUnstructuredSsContext, MAPApplicationContextVersion.version2), destAddress,
                destReference, origAddress, origReference);
        // The dataCodingScheme is still byte, as I am not exactly getting how
        // to encode/decode this.
        byte ussdDataCodingScheme = 0x0f;
        // USSD String: *125*+31628839999#
        // The Charset is null, here we let system use default Charset (UTF-7 as
        // explained in GSM 03.38. However if MAP User wants, it can set its own
        // impl of Charset
        USSDString ussdString = servFact.createUSSDString("*125*+31628839999#", null);
        AddressString msisdn = this.servFact.createAddressString(AddressNature.international_number,
                NumberingPlan.ISDN, "31628838002");
        mapDialog.addProcessUnstructuredSSRequest(ussdDataCodingScheme, ussdString, msisdn);
        // This will initiate the TC-BEGIN with INVOKE component
        mapDialog.send();
    

The complete example looks like



public class MAPExample implements MAPDialogListener, MAPServiceSupplementaryListener {
    private MAPStack mapStack;
    private MAPProvider mapProvider;
    MapServiceFactory servFact;
    SccpAddress destAddress = null;
    // The address created by passing the AddressNature, NumberingPlan and
    // actual address
    AddressString destReference = servFact.createAddressString(AddressNature.international_number,
            NumberingPlan.land_mobile, "204208300008002");
    SccpAddress origAddress = null;
    AddressString origReference = servFact.createAddressString(AddressNature.international_number, NumberingPlan.ISDN,
            "31628968300");
    MAPExample(SccpProvider sccpPprovider, SccpAddress address, SccpAddress remoteAddress) {
        origAddress = address;
        destAddress = remoteAddress;
        mapStack = new MAPStackImpl(sccpPprovider, 8);
        mapProvider = mapStack.getMAPProvider();
        servFact = mapProvider.getMapServiceFactory();
        mapProvider.addMAPDialogListener(this);
        mapProvider.getMAPServiceSupplementary().addMAPServiceListener(this);
    }
    private static SccpProvider getSccpProvider() throws NamingException {
        // no arg is ok, if we run in JBoss
        InitialContext ctx = new InitialContext();
        try {
            String providerJndiName = "/mobicents/ss7/sccp";
            return ((SccpStack) ctx.lookup(providerJndiName)).getSccpProvider();
        } finally {
            ctx.close();
        }
    }
    private static SccpAddress createLocalAddress() {
        return new SccpAddress(RoutingIndicator.ROUTING_BASED_ON_DPC_AND_SSN, 1, null, 8);
    }
    private static SccpAddress createRemoteAddress() {
        return new SccpAddress(RoutingIndicator.ROUTING_BASED_ON_DPC_AND_SSN, 2, null, 8);
    }
    public void run() throws Exception {
        // Make the supplimentary service activated
        mapProvider.getMAPServiceSupplementary().acivate();
        // First create Dialog
        MAPDialogSupplementary mapDialog = mapProvider.getMAPServiceSupplementary().createNewDialog(
                MAPApplicationContext.getInstance(MAPApplicationContextName.networkUnstructuredSsContext, MAPApplicationContextVersion.version2), destAddress,
                destReference, origAddress, origReference);
        // The dataCodingScheme is still byte, as I am not exactly getting how
        // to encode/decode this.
        byte ussdDataCodingScheme = 0x0f;
        // USSD String: *125*+31628839999#
        // The Charset is null, here we let system use default Charset (UTF-7 as
        // explained in GSM 03.38. However if MAP User wants, it can set its own
        // impl of Charset
        USSDString ussdString = servFact.createUSSDString("*125*+31628839999#", null);
        AddressString msisdn = this.servFact.createAddressString(AddressNature.international_number,
                NumberingPlan.ISDN, "31628838002");
        mapDialog.addProcessUnstructuredSSRequest(ussdDataCodingScheme, ussdString, msisdn);
        // This will initiate the TC-BEGIN with INVOKE component
        mapDialog.send();
    }
    public void onProcessUnstructuredSSIndication(ProcessUnstructuredSSIndication procUnstrInd) {
        // TODO Auto-generated method stub
    }
    public void onUnstructuredSSIndication(UnstructuredSSIndication unstrInd) {
        // TODO Auto-generated method stub
    }
    public static void main(String[] args) throws Exception {
        SccpProvider sccpProvider = getSccpProvider(); // JNDI lookup of SCCP
        SccpAddress localAddress = createLocalAddress();
        SccpAddress remoteAddress = createRemoteAddress();
        MAPExample example = new MAPExample(sccpProvider, localAddress, remoteAddress);
        example.run();
    }
    @Override
    public void onDialogRequest(MAPDialog mapDialog, AddressString destReference, AddressString origReference,
            MAPExtensionContainer extensionContainer) {
        // TODO Auto-generated method stub
    }
    @Override
    public void onDialogAccept(MAPDialog mapDialog, MAPExtensionContainer extensionContainer) {
        // TODO Auto-generated method stub
    }
    @Override
    public void onDialogReject(MAPDialog mapDialog, MAPRefuseReason refuseReason, MAPProviderError providerError,
            ApplicationContextName alternativeApplicationContext, MAPExtensionContainer extensionContainer) {
        // TODO Auto-generated method stub
    }
    @Override
    public void onDialogUserAbort(MAPDialog mapDialog, MAPUserAbortChoice userReason,
            MAPExtensionContainer extensionContainer) {
        // TODO Auto-generated method stub
    }
    @Override
    public void onDialogProviderAbort(MAPDialog mapDialog, MAPAbortProviderReason abortProviderReason,
            MAPAbortSource abortSource, MAPExtensionContainer extensionContainer) {
        // TODO Auto-generated method stub
    }
    @Override
    public void onDialogClose(MAPDialog mapDialog) {
        // TODO Auto-generated method stub
    }
    @Override
    public void onDialogDelimiter(MAPDialog mapDialog) {
        // TODO Auto-generated method stub
    }
    @Override
    public void onDialogNotice(MAPDialog mapDialog, MAPNoticeProblemDiagnostic noticeProblemDiagnostic) {
        // TODO Auto-generated method stub
    }
    public void onDialogResease(MAPDialog mapDialog) {
        
    }
    @Override
    public void onDialogTimeout(MAPDialog mapDialog) {
        // TODO Auto-generated method stub
        
    }
    @Override
    public void onErrorComponent(MAPDialog mapDialog, Long invokeId, MAPErrorMessage mapErrorMessage) {
        // TODO Auto-generated method stub
        
    }
    @Override
    public void onProviderErrorComponent(MAPDialog mapDialog, Long invokeId, MAPProviderError providerError) {
        // TODO Auto-generated method stub
        
    }
    @Override
    public void onRejectComponent(MAPDialog mapDialog, Long invokeId, Problem problem) {
        // TODO Auto-generated method stub
        
    }
    @Override
    public void onInvokeTimeout(MAPDialog mapDialog, Long invoke) {
        // TODO Auto-generated method stub
        
    }
}
    

The JBoss Communications Platform is written in Java; therefore, before running any JBoss Communications server, you must have a working Java Runtime Environment (JRE) or Java Development Kit (JDK) installed on your system. In addition, the JRE or JDK you are using to run JBoss Communications must be version 5 or higher[1].

Should I Install the JRE or JDK?

Although you can run JBoss Communications servers using the Java Runtime Environment, we assume that most users are developers interested in developing Java-based, JBoss Communications-driven solutions. Therefore, in this guide we take the tact of showing how to install the full Java Development Kit.

Should I Install the 32-Bit or the 64-Bit JDK, and Does It Matter?

Briefly stated: if you are running on a 64-Bit Linux or Windows platform, you should consider installing and running the 64-bit JDK over the 32-bit one. Here are some heuristics for determining whether you would rather run the 64-bit Java Virtual Machine (JVM) over its 32-bit cousin for your application:

  • Wider datapath: the pipe between RAM and CPU is doubled, which improves the performance of memory-bound applications when using a 64-bit JVM.

  • 64-bit memory addressing gives virtually unlimited (1 exabyte) heap allocation. However large heaps affect garbage collection.

  • Applications that run with more than 1.5 GB of RAM (including free space for garbage collection optimization) should utilize the 64-bit JVM.

  • Applications that run on a 32-bit JVM and do not require more than minimal heap sizes will gain nothing from a 64-bit JVM. Barring memory issues, 64-bit hardware with the same relative clock speed and architecture is not likely to run Java applications faster than their 32-bit cousin.

Note that the following instructions detail how to download and install the 32-bit JDK, although the steps are nearly identical for installing the 64-bit version.

Downloading

You can download the Sun JDK 5.0 (Java 2 Development Kit) from Sun's website: http://java.sun.com/javase/downloads/index_jdk5.jsp. Click on the Download link next to "JDK 5.0 Update <x>" (where <x> is the latest minor version release number). On the next page, select your language and platform (both architecture—whether 32- or 64-bit—and operating system), read and agree to the Java Development Kit 5.0 License Agreement, and proceed to the download page.

The Sun website will present two download alternatives to you: one is an RPM inside a self-extracting file (for example, jdk-1_5_0_16-linux-i586-rpm.bin), and the other is merely a self-extracting file (e.g. jdk-1_5_0_16-linux-i586.bin). If you are installing the JDK on Red Hat Enterprise Linux, Fedora, or another RPM-based Linux system, we suggest that you download the self-extracting file containing the RPM package, which will set up and use the SysV service scripts in addition to installing the JDK. We also suggest installing the self-extracting RPM file if you will be running JBoss Communications in a production environment.

Installing

The following procedures detail how to install the Java Development Kit on both Linux and Windows.

Important

You do not need to install a -compat package in addition to the JDK if you installed the self-extracting RPM file! The -compat package merely performs the same SysV service script set up that the RPM version of the JDK installer does.

Configuring

Configuring your system for the JDK consists in two tasks: setting the JAVA_HOME environment variable, and ensuring that the system is using the proper JDK (or JRE) using the alternatives command. Setting JAVA_HOME usually overrides the values for java, javac and java_sdk_1.5.0 in alternatives, but we will set them all just to be safe and consistent.

Setting the JAVA_HOME Environment Variable on Generic Linux

After installing the JDK, you must ensure that the JAVA_HOME environment variable exists and points to the location of your JDK installation.

Setting the JAVA_HOME Environment Variable on Linux

You can determine whether JAVA_HOME is set on your system by echoing it on the command line:

~]$ echo $JAVA_HOME

If JAVA_HOME is not set already, then you must set its value to the location of the JDK installation on your system. You can do this by adding two lines to your personal ~/.bashrc configuration file. Open ~/.bashrc (or create it if it doesn't exist) and add a line similar to the following one anywhere inside the file:

export JAVA_HOME="/usr/lib/jvm/jdk1.5.0_<version>"

You should also set this environment variable for any other users who will be running JBoss Communications (any environment variables exported from ~/.bashrc files are local to that user).

Setting java, javac and java_sdk_1.5.0 Using the alternatives command
Selecting the Correct System JVM on Linux using alternatives

On systems with the alternatives command, including Red Hat Enterprise Linux and Fedora, you can easily choose which JDK (or JRE) installation you wish to use, as well as which java and javac executables should be run when called.

As the root user, call /usr/sbin/alternatives with the --config java option to select between JDKs and JREs installed on your system:

root@localhost ~]$ /usr/sbin/alternatives --config java

There are 3 programs which provide 'java'.

  Selection    Command
-----------------------------------------------
   1           /usr/lib/jvm/jre-1.5.0-gcj/bin/java
   2           /usr/lib/jvm/jre-1.6.0-sun/bin/java
*+ 3         /usr/lib/jvm/jre-1.5.0-sun/bin/java


Enter to keep the current selection[+], or type selection number:

In our case, we want to use the Sun JDK, version 5, that we downloaded and installed, to run the java executable. In the alternatives information printout above, a plus (+) next to a number indicates the one currently being used. As per alternatives' instructions, pressing Enter will simply keep the current JVM, or you can enter the number corresponding to the JVM you would prefer to use.

Repeat the procedure above for the javac command and the java_sdk_1.5.0 environment variable, as the root user:

~]$ /usr/sbin/alternatives --config javac
~]$ /usr/sbin/alternatives --config java_sdk_1.5.0
Setting the JAVA_HOME Environment Variable on Windows

For information on how to set environment variables in Windows, refer to http://support.microsoft.com/kb/931715.

Testing

Finally, to make sure that you are using the correct JDK or Java version (5 or higher), and that the java executable is in your PATH, run the java -version command in the terminal from your home directory:

~]$ java -version
java version "1.5.0_16"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_16-b03)
Java HotSpot(TM) Client VM (build 1.5.0_16-b03, mixed mode, sharing)
Uninstalling

There is usually no reason (other than space concerns) to remove a particular JDK from your system, given that you can switch between JDKs and JREs easily using alternatives, and/or by setting JAVA_HOME.

Uninstalling the JDK on Linux

On RPM-based systems, you can uninstall the JDK using the yum remove <jdk_rpm_name> command.

Uninstalling the JDK on Windows

On Windows systems, check the JDK entry in the Start menu for an uninstall command, or use Add/Remove Programs.



[1] At this point in time, it is possible to run most JBoss Communications servers, such as the JAIN SLEE, using a Java 6 JRE or JDK. Be aware, however, that presently the XML Document Management Server does not run on Java 6. We suggest checking the JBoss Communications web site, forums or discussion pages if you need to inquire about the status of running the XML Document Management Server with Java 6.

The JBoss Communications Platform (JBoss Communications) is built on top of the JBoss Enterprise Application Platform. You do not need to set the JBOSS_HOME environment variable to run any of the JBoss Communications Platform servers unless JBOSS_HOME is already set.

The best way to know for sure whether JBOSS_HOME was set previously or not is to perform a simple check which may save you time and frustration.

Checking to See If JBOSS_HOME is Set on Unix

At the command line, echo $JBOSS_HOME to see if it is currently defined in your environment:

~]$ echo $JBOSS_HOME

The JBoss Communications Platform and most JBoss Communications servers are built on top of the JBoss Enterprise Application Platform (JBoss Enterprise Application Platform). When the JBoss Communications Platform or JBoss Communications servers are built from source, then JBOSS_HOME must be set, because the JBoss Communications files are installed into (or “over top of” if you prefer) a clean JBoss Enterprise Application Platform installation, and the build process assumes that the location pointed to by the JBOSS_HOME environment variable at the time of building is the JBoss Enterprise Application Platform installation into which you want it to install the JBoss Communications files.

This guide does not detail building the JBoss Communications Platform or any JBoss Communications servers from source. It is nevertheless useful to understand the role played by JBoss AS and JBOSS_HOME in the JBoss Communications ecosystem.

The immediately-following section considers whether you need to set JBOSS_HOME at all and, if so, when. The subsequent sections detail how to set JBOSS_HOME on Unix and Windows

You DO NOT NEED to set JBOSS_HOME if...

You MUST set JBOSS_HOME if...

Naturally, if you installed the JBoss Communications Platform or one of the JBoss Communications server binary releases which do not bundle JBoss Enterprise Application Platform, yet requires it to run, then you should install before setting JBOSS_HOME or proceeding with anything else.

Setting the JBOSS_HOME Environment Variable on Unix

The JBOSS_HOME environment variable must point to the directory which contains all of the files for the JBoss Communications Platform or individual JBoss Communications server that you installed. As another hint, this topmost directory contains a bin subdirectory.

Setting JBOSS_HOME in your personal ~/.bashrc startup script carries the advantage of retaining effect over reboots. Each time you log in, the environment variable is sure to be set for you, as a user. On Unix, it is possible to set JBOSS_HOME as a system-wide environment variable, by defining it in /etc/bashrc, but this method is neither recommended nor detailed in these instructions.

Procedure B.1. To Set JBOSS_HOME on Unix...

  1. Open the ~/.bashrc startup script, which is a hidden file in your home directory, in a text editor, and insert the following line on its own line while substituting for the actual install location on your system:

    export JBOSS_HOME="/home/<username>/<path>/<to>/<install_directory>"
  2. Save and close the .bashrc startup script.

  3. You should source the .bashrc script to force your change to take effect, so that JBOSS_HOME becomes set for the current session[2].

    ~]$ source ~/.bashrc
  4. Finally, ensure that JBOSS_HOME is set in the current session, and actually points to the correct location:

    Note

    The command line usage below is based upon a binary installation of the JBoss Communications Platform. In this sample output, JBOSS_HOME has been set correctly to the topmost_directory of the JBoss Communications installation. Note that if you are installing one of the standalone JBoss Communications servers (with JBoss AS bundled!), then JBOSS_HOME would point to the topmost_directory of your server installation.

    ~]$ echo $JBOSS_HOME
    /home/silas/<path>/<to>/<install_directory>
Setting the JBOSS_HOME Environment Variable on Windows

The JBOSS_HOME environment variable must point to the directory which contains all of the files for the JBoss Communications Platform or individual JBoss Communications server that you installed. As another hint, this topmost directory contains a bin subdirectory.

For information on how to set environment variables in recent versions of Windows, refer to http://support.microsoft.com/kb/931715.



[2] Note that any other terminals which were opened prior to your having altered .bashrc will need to source ~/.bashrc as well should they require access to JBOSS_HOME.

Revision History
Revision 1.0Wed June 2 2010Bartosz Baranowski
Creation of the JBoss Communications SS7 Stack User Guide.
Revision 1.1Tue Dec 21 2010Amit Bhayani
Creation of the JBoss Communications SS7 Stack User Guide.